home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 7: Sunsite / Linux Cubed Series 7 - Sunsite Vol 1.iso / system / network / daemons / dns / bind-4.9 / bind-4 / usr / man / man3 / gethostbyname.3 next >
Encoding:
Text File  |  1995-08-04  |  7.1 KB  |  199 lines
  1.  
  2.  
  3.  
  4. GETHOSTBYNAME(3)                                 GETHOSTBYNAME(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        gethostbyname, gethostbyaddr, gethostent, sethostent, end-
  9.        hostent, herror - get network host entry
  10.  
  11. SSYYNNOOPPSSIISS
  12.        ##iinncclluuddee <<nneettddbb..hh>>
  13.  
  14.        eexxtteerrnn iinntt hh__eerrrrnnoo;;
  15.  
  16.        ssttrruucctt hhoosstteenntt **ggeetthhoossttbbyynnaammee((nnaammee))
  17.        cchhaarr **nnaammee;;
  18.  
  19.        ssttrruucctt hhoosstteenntt **ggeetthhoossttbbyyaaddddrr((aaddddrr,, lleenn,, ttyyppee))
  20.        cchhaarr **aaddddrr;; iinntt lleenn,, ttyyppee;;
  21.  
  22.        ssttrruucctt hhoosstteenntt **ggeetthhoosstteenntt(())
  23.  
  24.        sseetthhoosstteenntt((ssttaayyooppeenn))
  25.        iinntt ssttaayyooppeenn;;
  26.  
  27.        eennddhhoosstteenntt(())
  28.  
  29.        hheerrrroorr((ssttrriinngg))
  30.        cchhaarr **ssttrriinngg;;
  31.  
  32.  
  33. DDEESSCCRRIIPPTTIIOONN
  34.        _G_e_t_h_o_s_t_b_y_n_a_m_e and _g_e_t_h_o_s_t_b_y_a_d_d_r each return a  pointer  to
  35.        an  object  with  the  following  structure  describing an
  36.        internet host referenced by name or  by  address,  respec-
  37.        tively.   This  structure  contains either the information
  38.        obtained from the name  server,  _n_a_m_e_d(8),  or  broken-out
  39.        fields  from  a  line  in  _/_e_t_c_/_h_o_s_t_s.   If the local name
  40.        server is not  running  these  routines  do  a  lookup  in
  41.        _/_e_t_c_/_h_o_s_t_s.
  42.  
  43.               struct    hostent {
  44.                    char *h_name;  /* official name of host */
  45.                    char **h_aliases;   /* alias list */
  46.                    int  h_addrtype;    /* host address type */
  47.                    int  h_length; /* length of address */
  48.                    char **h_addr_list; /* list of addresses from name server */
  49.               };
  50.               #define   h_addr  h_addr_list[0]   /* address, for backward compatibility */
  51.  
  52.        The members of this structure are:
  53.  
  54.        h_name       Official name of the host.
  55.  
  56.        h_aliases    A  zero  terminated  array of alternate names
  57.                     for the host.
  58.  
  59.        h_addrtype   The type of address being returned; currently
  60.                     always AF_INET.
  61.  
  62.  
  63.  
  64.                           June 23, 1990                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GETHOSTBYNAME(3)                                 GETHOSTBYNAME(3)
  71.  
  72.  
  73.        h_length     The length, in bytes, of the address.
  74.  
  75.        h_addr_list  A  zero terminated array of network addresses
  76.                     for the host.  Host addresses are returned in
  77.                     network byte order.
  78.  
  79.        h_addr       The first address in h_addr_list; this is for
  80.                     backward compatiblity.
  81.  
  82.        When using the nameserver, _g_e_t_h_o_s_t_b_y_n_a_m_e will  search  for
  83.        the  named  host  in  the  current  domain and its parents
  84.        unless the name ends in a dot.  If the  name  contains  no
  85.        dot, and if the environment variable ``HOSTALAIASES'' con-
  86.        tains the name of an alias file, the alias file will first
  87.        be  searched  for  an  alias matching the input name.  See
  88.        _h_o_s_t_n_a_m_e(7) for the domain search procedure and the  alias
  89.        file format.
  90.  
  91.        _S_e_t_h_o_s_t_e_n_t  may  be used to request the use of a connected
  92.        TCP socket for queries.  If the _s_t_a_y_o_p_e_n flag is non-zero,
  93.        this  sets  the  option  to  send  all queries to the name
  94.        server using TCP and to retain the connection  after  each
  95.        call   to   _g_e_t_h_o_s_t_b_y_n_a_m_e  or  _g_e_t_h_o_s_t_b_y_a_d_d_r.   Otherwise,
  96.        queries are performed using UDP datagrams.
  97.  
  98.        _E_n_d_h_o_s_t_e_n_t closes the TCP connection.
  99.  
  100. DDIIAAGGNNOOSSTTIICCSS
  101.        Error return status from _g_e_t_h_o_s_t_b_y_n_a_m_e  and  _g_e_t_h_o_s_t_b_y_a_d_d_r
  102.        is  indicated  by  return of a null pointer.  The external
  103.        integer _h___e_r_r_n_o may then be checked to see whether this is
  104.        a  temporary  failure  or an invalid or unknown host.  The
  105.        routine _h_e_r_r_o_r can be  used  to  print  an  error  message
  106.        describing  the  failure.   If its argument _s_t_r_i_n_g is non-
  107.        NULL, it is printed, followed by a colon and a space.  The
  108.        error message is printed with a trailing newline.
  109.  
  110.        _h___e_r_r_n_o can have the following values:
  111.  
  112.               HOST_NOT_FOUND  No such host is known.
  113.  
  114.               TRY_AGAIN       This  is  usually a temporary error
  115.                               and means that the local server did
  116.                               not  receive  a  response  from  an
  117.                               authoritative server.  A  retry  at
  118.                               some later time may succeed.
  119.  
  120.               NO_RECOVERY     Some  unexpected server failure was
  121.                               encountered.   This   is   a   non-
  122.                               recoverable error.
  123.  
  124.               NO_DATA         The  requested  name  is  valid but
  125.                               does not have an IP  address;  this
  126.                               is  not  a  temporary  error.  This
  127.  
  128.  
  129.  
  130.                           June 23, 1990                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. GETHOSTBYNAME(3)                                 GETHOSTBYNAME(3)
  137.  
  138.  
  139.                               means that the name is known to the
  140.                               name server but there is no address
  141.                               associated with this name.  Another
  142.                               type  of request to the name server
  143.                               using this domain name will  result
  144.                               in  an answer; for example, a mail-
  145.                               forwarder  may  be  registered  for
  146.                               this domain.
  147.  
  148. FFIILLEESS
  149.        /etc/hosts
  150.  
  151. SSEEEE AALLSSOO
  152.        resolver(3), hosts(5), hostname(7), named(8)
  153.  
  154. CCAAVVEEAATT
  155.        _G_e_t_h_o_s_t_e_n_t  is  defined, and _s_e_t_h_o_s_t_e_n_t and _e_n_d_h_o_s_t_e_n_t are
  156.        redefined, when _l_i_b_c is built to use only the routines  to
  157.        lookup in _/_e_t_c_/_h_o_s_t_s and not the name server.
  158.  
  159.        _G_e_t_h_o_s_t_e_n_t  reads the next line of _/_e_t_c_/_h_o_s_t_s, opening the
  160.        file if necessary.
  161.  
  162.        _S_e_t_h_o_s_t_e_n_t is redefined to open and rewind the  file.   If
  163.        the  _s_t_a_y_o_p_e_n  argument  is  non-zero, the hosts data base
  164.        will not be closed after each  call  to  _g_e_t_h_o_s_t_b_y_n_a_m_e  or
  165.        _g_e_t_h_o_s_t_b_y_a_d_d_r.  _E_n_d_h_o_s_t_e_n_t is redefined to close the file.
  166.  
  167. BBUUGGSS
  168.        All information is contained in a static area so  it  must
  169.        be copied if it is to be saved.  Only the Internet address
  170.        format is currently understood.
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                           June 23, 1990                         3
  197.  
  198.  
  199.